home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 016a / love4th.zip / REDEFINE.DOC < prev    next >
Text File  |  1991-10-01  |  7KB  |  205 lines
  1.                Redefining and Revectoring Forth Definitions
  2.                ============================================
  3. Concept
  4. -------
  5.  
  6. In constructing Forth application programmes, words are defined by
  7. using previously defined words as building blocks. This bottom-up
  8. process precludes the use of forward referencing or mutual recursion
  9. but is normally sufficient to build quite complex software.
  10. There are many occasions though, when the ability to reference a word
  11. before it has been defined or, for example, when the action of a low
  12. level word needs to be changed dynamically (ie. during program
  13. execution), that a portable and convenient method to do this becomes
  14. necessary.
  15.  
  16. Definition of Terms
  17. -------------------
  18.  
  19. Redefine:      A word is redefined when its action is changed after its
  20.                definition has been compiled. Redefinition can occur
  21.                dynamically  at run-time but is generally used to
  22.                permanently change the the action of a word.
  23.  
  24. Revector:      Revectoring a word refers to the changing of the action
  25.                of a Forth word at run-time. This is the prefered method
  26.                for changing a word's action many times at run-time.
  27.  
  28. Vector:        A vector is the information necessary to execute a word
  29.                as if it had been compiled into a definition or typed on
  30.                the command line. The vector information is system
  31.                specific but should be hidden from the programmer so
  32.                that code which uses redefinitions, or allows run-time
  33.                revectoring, can be ported to other systems or computer
  34.                architectures. The vector is kept in a location called a
  35.                vector field, known to the dynamic word.
  36.  
  37. Reasons for Redefining and Revectoring
  38. --------------------------------------
  39.  
  40. (1)  To change the action of a low level word that is the foundation
  41.      for many other higher level words when it is inconvenient to
  42.      recompile the entire system.
  43.  
  44. (2)  To allow mutual recursion or forward referencing. This is
  45.      accomplished by first defining a dummy word and then later
  46.      redefining it to perform its correct action.
  47.  
  48. (3)  To dynamically redirect input or output within an application
  49.      while allowing higher level words to be device independant.
  50.  
  51. (4)  To develop and test an application interactively and then change
  52.      the action of hardware specific words before committing the code
  53.      to EPROM.
  54.  
  55. (5)  To chain abort handlers or other error handlers together to
  56.      accomplish application specific actions on run-time execution
  57.      errors.
  58.  
  59. Word List
  60. ---------
  61.  
  62. REDEFINE  ( -- )
  63.      Used in the form:
  64.           Redefine <word1>  <word2>
  65.  
  66.      and can be read as "redefine <word1> do the same thing as
  67.      <word2>".
  68.  
  69. RESTORE  ( -- )
  70.      Used in the form:
  71.           RESTORE <word>
  72.  
  73.      where <word> has been previously  redefined, RESTORE will restore
  74.      the original function of <word>.
  75.  
  76. MAKE_DYNAMIC  ( -- )
  77.      Used in the form:
  78.           MAKE_DYNAMIC <word>
  79.  
  80.      to make <word> dynamically revectorable.
  81.      This allots space in the dictionary for a vector field, extracts the
  82.      vector from <word>, stores the vector into the vector field and 
  83.      alters the code field address of <word> so that when <word> 
  84.      executes it finds the vector in its vector field and executes it.
  85.  
  86.  
  87. REVECTOR  ( -- )
  88.      An immediate word used in the form:
  89.  
  90.           REVECTOR <word1> <word2>
  91.      where <word1> is a dynamically revectorable word. <word2> is any
  92.      other Forth word. Revector changes the vector field at <word1> by
  93.      storing the vector extracted from <word2>.
  94.  
  95.  
  96. VECTOR_FROM    ( -- )(compiling)
  97.                ( -- cfa, contents_of_cfa )(executing)
  98.           An immediate word used in the form:
  99.                VECTOR_FROM <word>
  100.  
  101.      From the next word in the input stream extract the cfa and the
  102.      contents of the cfa . If the state is compiling, then the vector
  103.      is compiled as a dliteral. This word operates on any Forth word.
  104.  
  105.  
  106. EXECUTE_VECTOR  ( cfa, contents_of_cfa -- )
  107.           Executes the word specified by the two-part vector on the
  108.           stack.
  109.  
  110.  
  111. GETVECTOR  ( -- )( compiling )
  112.            ( -- cfa, cfa_contents )( executing )
  113.  
  114.           An immediate word used in the form:
  115.                GETVECTOR <word>
  116.  
  117.           where <word> is a dynamically revectorable word. If the state
  118.           is compiling then GETVECTOR compiles the cfa of <word> as a
  119.           literal followed by <GETVECTOR>. This word is used to
  120.           retrieve the vector from the vector field of <word>, to be
  121.           stored in a variable, passed to EXECUTE_VECTOR or operated on
  122.           later with SETVECTOR.
  123.  
  124. SETVECTOR ( cfa1, cfa1_contents -- )(executing)
  125.           ( -- )(compiling)
  126.           An immediate word used in the form:
  127.                SETVECTOR <word>
  128.  
  129.           where <word> is a dynamically revectorable word. When
  130.           compiling, SETVECTOR compiles the cfa of <word> as a literal
  131.           followed by <SETVECTOR>. This word is used to store the
  132.           vector that is on the stack at run-time into the vector field
  133.           of <word>.
  134.  
  135. Examples
  136. --------
  137.  
  138.      Forward Referencing:
  139.  
  140.           : second_word ;     ( make a dummy )
  141.  
  142.  
  143.           ( a word which executes another word that is define later )
  144.           : first_word  ( -- )
  145.                second_word ;
  146.  
  147.           ( the second word executes the previously defined word)
  148.           : <second_word> ( -- )
  149.                first_word  ;
  150.  
  151.  
  152.           ( now complete the circle by making second_word execute )
  153.           ( something useful  )
  154.           redefine second_word <second_word>
  155.  
  156.  
  157.  
  158.      Input and Output Redirection:
  159.  
  160.  
  161.      make_dynamic emit   ( make emit dynamically revectorable )
  162.  
  163.      ( output a character in textmode to the LCD Display )
  164.      : LCD_text_EMIT ( c -- )
  165.          dup bl <
  166.          if
  167.              case
  168.                  7   of beep     endof
  169.                  8   of do_backspace endof
  170.                  9   of do_tab   endof
  171.                  10  of do_linefeed  endof
  172.                  13  of do_return    endof
  173.              endcase
  174.          else
  175.              LCDwrite lcd!       ( write the char )
  176.              1 #out +!
  177.              1 cursor_addr +!
  178.              #out @ chars/line  =    ( is cursor past last column? )
  179.              if  do_return
  180.                  do_linefeed
  181.              then
  182.  
  183.          then
  184.       ;
  185.  
  186.  
  187. \     Later ...
  188.  
  189.      : app_word ( n1 n2 -- )
  190.           ...
  191.           revector emit  LCD_text_EMIT
  192.           ...  ;
  193.  
  194.  
  195.  
  196.      Chaining error handlers and abort handlers:
  197.  
  198.      ( a new abort that executes the old abort afterwards )
  199.      : <locals_abort>  ( -- )
  200.          LP!                  ( initialize the local stack )
  201.          <cleanup_locals>     ( restore all pointers and flags )
  202.          vector_from abort  execute_vector   ; ( execute previous abort)
  203.  
  204.      ( chain the special abort handler before abort )
  205.      redefine abort  <locals_abort>